OpenEdge Development: <br />Web Services SOAP header structure

The following XML contains a SOAP header as it might appear inside a SOAP message:

SOAP message with header
<soap:Envelope> xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> . . . `<soap:Header>` `<q1:OrderInfoID` `xmlns:q1="http://www.example.com/webservices/OrderInfo"` `SOAP-ENV:mustUnderstand="1"` `SOAP-ENV:actor="/WSA">` `<uuid xsi:type="xsd:string">12345-67890-98765-4321</uuid>` `</q1:OrderInfoID>` `<t:Transaction` `xmlns:t="http://www.example.com/webservices/Transaction"` `SOAP-ENV:mustUnderstand="1" t:stepnum="1">` `<t:TransID>5</t:TransID>` `<t:SubID>871</t:SubID>` `</t:Transaction>` `</soap:Header>` <soap:Body ...> <`parameter-element`> ... </`parameter-element`> . . . </soap:Body> </soap:Envelope >

<soap:Envelope> 
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
   . . . 
   <soap:Header> 
      <q1:OrderInfoID 
                   xmlns:q1="http://www.example.com/webservices/OrderInfo" 
                   SOAP-ENV:mustUnderstand="1" 
                   SOAP-ENV:actor="/WSA"> 
         <uuid xsi:type="xsd:string">12345-67890-98765-4321</uuid> 
      </q1:OrderInfoID> 
      <t:Transaction 
                   xmlns:t="http://www.example.com/webservices/Transaction" 
                   SOAP-ENV:mustUnderstand="1" t:stepnum="1"> 
         <t:TransID>5</t:TransID> 
         <t:SubID>871</t:SubID> 
      </t:Transaction> 
   </soap:Header> 
   <soap:Body ...> 
      <parameter-element> ... </parameter-element>  
      . . . 
   </soap:Body> 
</soap:Envelope >

As you can see, the <Header> element is, itself, nothing more than a container for other elements, the application-specific header entry elements. Any parameters generated for an operation in this SOAP message appear in the <Body> element in much the same way.

In this case, the SOAP header contains two header entries, named q1:OrderInfoID and t:Transaction (where q1: and t: are namespace prefixes). Each of these elements has a series of attributes and contains one or more child elements. The <q1:OrderInfoID> element contains one child element named uuid, and the <t:Transaction> element contains two child elements, named t:TransID and t:SubID. All of these element names are application-defined.

Accessing the SOAP header

To access the SOAP header and its elements from your 4GL application, you define callback procedures using specific signatures to use as header handlers, depending on whether the procedure is used to access a SOAP response header or a SOAP request header. As a minimum, you might not have to access message headers at all. If you need to access the headers, you can define one header handler to manage all of the SOAP request headers and another header handler to manage all of the SOAP response headers that are generated for operations of a single Web service procedure object. You can specify the handlers for a Web service procedure object by invoking the SET-CALLBACK-PROCEDURE( ) method on the corresponding procedure handle. If you want to add additional handlers for the same port type managed by a Web service procedure object, you must map the port type using additional procedure objects. For more information, see the information on specifying header callback procedures in Chapter 10, " Invoking Web Service Operations from the Progress 4GL."

Every time you invoke an operation for a port type where you have specified header handlers, the handlers execute as part of the operation invocation. They intercept and manage the SOAP headers as part of sending a SOAP request message, before the message is sent to the Web service, and as part of receiving a SOAP response message, before any message parameters are passed to complete invocation of the operation.

Requirements for header handlers

Note that there is no absolute requirement to use header handlers. The need for managing headers depends entirely on the requirements of the Web service that you are accessing. You can also set and reset the callbacks for header handlers as often as you need to specify the correct handlers for different operations and port types, add additional header handlers for a single port type by mapping the port type to additional Web service procedure objects, and you can remove any previously specified callbacks entirely when you have no need to handle the SOAP headers for an operation or port type. The only absolute requirement for a header handler is the signature that you must use to define it.